---
title: 국제화
description: Astro에서 i18n 라우팅을 사용하는 방법을 알아보세요.
i18nReady: false
---

import { FileTree } from '@astrojs/starlight/components';
import Since from '~/components/Since.astro';

Astro의 국제화 (i18n) 기능을 사용하면 전 세계의 방문자들을 대상으로 프로젝트를 조정할 수 있습니다.

## i18n 라우팅

<p>
  <Since v="3.5.0" />
</p>

Astro의 i18n 라우팅을 사용하면 기본 언어 구성, 상대 페이지 URL 계산, 방문자 브라우저에서 제공하는 기본 언어 허용을 지원하여 다국어 콘텐츠를 추가할 수 있습니다. 방문자가 항상 사이트의 기존 콘텐츠로 이동할 수 있도록 언어별로 대체 언어를 지정할 수도 있습니다.

이 라우팅 API는 다국어 사이트가 생성하는 URL을 생성, 사용, 확인하는 데 도움이 됩니다. 이 API가 계속 개발됨에 따라 최신 기능을 정기적으로 확인하고 업데이트하세요!

### i18n 라우팅 구성

1. [기본 언어 (`defaultLocale`) 및 지원할 모든 언어 목록 (`locales`)](#defaultlocale-및-locales)을 사용하여 Astro 구성에 `i18n` 객체를 추가하여 라우팅 옵션을 활성화합니다.

   ```js title="astro.config.mjs"
   import { defineConfig } from 'astro/config';
   export default defineConfig({
     i18n: {
       defaultLocale: 'en',
       locales: ['en', 'es', 'pt-br'],
     },
   });
   ```

2. `defaultLocale`에 대해 원하는 URL 경로를 기반으로 [`routing`](#라우팅)을 선택하고 구성합니다.

   - `"prefixDefaultLocale: false"` (기본값): 기본 언어로 된 URL에는 `/[locale]/` 접두사가 **없습니다**. 다른 모든 언어에는 접두사가 추가됩니다.
   - `"prefixDefaultLocale: true"`: 기본 언어를 포함한 모든 URL에는 `/[locale]/` 접두사가 붙습니다.

   ```js title="astro.config.mjs" ins={7}
   import { defineConfig } from 'astro/config';
   export default defineConfig({
     i18n: {
       defaultLocale: 'en',
       locales: ['es', 'en', 'fr'],
       routing: {
         prefixDefaultLocale: false,
       },
     },
   });
   ```

3. 언어별로 현지화된 콘텐츠로 콘텐츠 폴더를 구성합니다. 폴더 이름은 `locales`의 항목과 정확히 일치해야 하며, 폴더 구성은 [`routing`](#라우팅)에서 선택한 URL 경로와 일치해야 합니다.

   현지화된 URL 경로를 표시하도록 `prefixDefaultLocale: true`를 구성한 경우에만 `defaultLocale`에 대한 현지화된 폴더를 포함하세요.

   <FileTree>
     - src - pages - about.astro - index.astro - es - about.astro - index.astro - pt-br -
     about.astro - index.astro
   </FileTree>

   :::note
   현지화된 폴더는 `/pages/` 폴더의 루트에 있을 필요는 없습니다.

   `src/pages/` 내 어디에나 개별 `/[locale]/` 폴더를 생성하면 Astro의 [파일 기반 라우팅](/ko/guides/routing/)이 해당 URL 경로에 페이지를 생성합니다.
   :::

4. i18n 라우팅이 구성되면 이제 [`astro:i18n` 모듈](#가상-모듈-astroi18n)에서 사용할 수 있는 [`getRelativeLocaleURL()`](#getrelativelocaleurl) 도우미를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 이는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다. 링크를 수동으로 작성할 수도 있습니다.

   ```astro title="src/pages/es/index.astro"
   ---
   import { getRelativeLocaleUrl } from 'astro:i18n';

   // 기본 언어는 "es"
   const aboutURL = getRelativeLocaleUrl('es', 'about');
   ---

   <a href="/get-started/">¡Vamos!</a>
   <a href={getRelativeLocaleUrl('es', 'blog')}>Blog</a>
   <a href={aboutURL}>Acerca</a>
   ```

### `라우팅`

Astro의 내장 파일 기반 라우팅은 `src/pages/` 디렉터리의 파일 구조를 기반으로 URL 경로를 자동으로 생성합니다. i18n 라우팅을 구성할 때 `routing` 값을 사용하면 도우미 기능을 사용하여 프로젝트에서 경로를 생성, 사용, 확인할 수 있도록 파일 구조 (및 생성된 URL 경로)를 지정할 수 있습니다.

#### `prefixDefaultLocale: false`

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    routing: {
      prefixDefaultLocale: false,
    },
  },
});
```

이것이 **기본값**입니다. 기본 언어의 URL에 `/[locale]/` 접두사가 **없으며** 기본 언어의 파일이 `src/pages/` 루트에 존재하는 경우 이 옵션을 설정하십시오.

- `src/pages/blog.astro`는 `example.com/blog/` 경로를 생성합니다.
- `src/pages/fr/blog.astro`는 `example.com/fr/blog/` 경로를 생성합니다.
- `src/pages/es/blog.astro` 파일이 없으면 [대체 전략](#대체-전략)를 지정하지 않는 한 `example.com/es/blog/` 경로는 404가 됩니다.

#### `prefixDefaultLocale: true`

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    routing: {
      prefixDefaultLocale: true,
    },
  },
});
```

모든 경로의 URL에 `/locale/` 접두사가 있고 `defaultLocale`에 대한 파일을 포함한 모든 페이지 콘텐츠 파일이 현지화된 폴더에 있는 경우 이 옵션을 설정하세요.

    <FileTree>
    - src
      - pages
        - **index.astro** // 참고: 이 파일은 항상 필요합니다.
        - en
          - index.astro
          - about.astro
        - es
          - about.astro
          - index.astro
        - pt-br
          - about.astro
          - index.astro
    </FileTree>

- 언어 접두사가 없는 URL (예: `example.com/blog/`)은 404 (찾을 수 없음) 상태 코드를 반환합니다.

#### `redirectToDefaultLocale`

<p>
  <Since v="4.2.0" />
</p>

`src/pages/index.astro`에 의해 생성된 홈 URL (`/`)이 `/<defaultLocale>`로 리디렉션되는지 여부를 구성합니다.

`prefixDefaultLocale: true`를 설정하면 `routing` 구성 객체에서 `redirectToDefaultLocale: true`도 자동으로 설정됩니다. 기본적으로 필수 `src/pages/index.astro` 파일은 자동으로 기본 로케일의 인덱스 페이지로 리디렉션됩니다.

[`redirectToDefaultLocale: false` 설정](/ko/reference/configuration-reference/#i18nroutingredirecttodefaultlocale)을 통해 이 동작을 선택 해제할 수 있습니다. 이를 통해 구성된 로케일 폴더 구조 외부에 존재하는 사이트 홈 페이지를 가질 수 있습니다.

#### `domains` (실험적)

<p>
  <Since v="4.3.0" />
</p>

이 라우팅 옵션을 사용하면 `site`가 구성된 [`@astrojs/node`](/ko/guides/integrations-guide/node/) 또는 [`@astrojs/vercel`](/ko/guides/integrations-guide/vercel/) 어댑터를 사용하여 `서버` 렌더링 프로젝트에 대해 언어별로 도메인을 사용자 정의할 수 있습니다.

프로젝트에서 이를 활성화하려면, 아직 구성하지 않은 경우 기본 설정으로 [i18n 라우팅을 구성](#i18n-라우팅-구성)하세요. 그런 다음 `experimental.i18nDomains` 플래그를 `true`로 설정하고 `i18n.domains`를 추가하여 지원되는 `locales`을 사용자 정의 URL에 매핑합니다.

```js title="astro.config.mjs" {3-7} ins={14-21}
import { defineConfig } from 'astro/config';
export default defineConfig({
  site: 'https://example.com',
  output: 'server', // 필수, 사전 렌더링된 페이지 없음
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr', 'ja'],
    routing: {
      prefixDefaultLocale: false,
    },
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es',
    },
  },
  experimental: {
    i18nDomains: true,
  },
});
```

매핑되지 않은 모든 `locales`는 `prefixDefaultLocales` 구성을 따릅니다. 그러나 이 값이 `false`인 경우에도 `defaultLocale`에 대한 페이지 파일은 현지화된 폴더 내에 있어야 합니다. 위 구성을 위해서는 `/en/` 폴더가 필요합니다.

위 구성을 사용하면 다음과 같습니다.

- `/fr/about.astro` 파일은 `https://fr.example.com/about` URL을 생성합니다.
- `/es/about.astro` 파일은 `https://example.es/about` URL을 생성합니다.
- `/ja/about/astro` 파일은 `https://example.com/ja/about` URL을 생성합니다.
- `/en/about.astro` 파일은 `https://example.com/about` URL을 생성합니다.

위 URL은 `getAbsoluteLocaleUrl()` 및 `getAbsoluteLocaleUrlList()` 함수에서도 반환됩니다.

##### 제한사항

이 기능에는 몇 가지 제한사항이 있습니다.

- `site` 옵션은 필수입니다.
- `output` 옵션은 `"server"`로 설정되어야 합니다.
- 사전 렌더링된 개별 페이지는 있을 수 없습니다.
- 어댑터의 [`functionPerRoute`](/ko/reference/adapter-reference/#functionperroute) 기능은 지원되지 않습니다.

Astro는 이 기능을 지원하기 위해 다음 헤더를 사용합니다.

- [`X-Forwarded-Host`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Forwarded-Host) 및 [`Host`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Host). Astro는 전자를 사용하고, 없을 경우 후자를 시도할 것입니다.
- 서버 요청의 [`X-Forwarded-Proto`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Forwarded-Proto) 및 [`URL#protocol`](https://developer.mozilla.org/ko/docs/Web/API/URL/protocol).

서버 프록시/호스팅 플랫폼이 이 정보를 제공할 수 있는지 확인하세요. 이러한 헤더를 검색하지 못하면 404 (상태 코드) 페이지가 표시됩니다.

### `defaultLocale` 및 `locales`

`i18n` 라우팅 구성에는 기본 언어 ([`defaultLocale`](/ko/reference/configuration-reference/#i18ndefaultlocale))와 지원되는 모든 언어 목록 ([`locales`](/ko/reference/configuration-reference/#i18nlocales))이 모두 지정되어야 합니다.

`locales` 구성 배열의 각 항목은 문자열 (예: `"fr"`, `"pt-br"`) 또는 [사용자 정의 언어 경로](#사용자-정의-언어-경로)여야 합니다. `locales`에는 문자열과 사용자 정의 경로의 조합이 포함될 수 있습니다.

`/[locale]/` 폴더 이름은 목록의 `locales` (문자열 또는 `path` 값)과 정확히 일치해야 하며, [라우팅](#라우팅) 구성은 기본 언어에 대한 현지화된 폴더가 있는지 여부와 일치해야 합니다. 기타 지원되는 모든 언어에는 현지화된 자체 폴더가 있어야 합니다.

배포 호스트에 따라 URL 경로의 변환을 발견할 수 있으므로 배포된 사이트를 확인하여 `locale` 값에 가장 적합한 구문을 결정하세요.

### 사용자 정의 언어 경로

사이트에서 지원되는 `locales`를 문자열 (예: "en", "pt-br")로 정의하는 것 외에도 Astro를 사용하면 [브라우저에서 인식할 수 있는 임의 개수의 언어 `codes`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept-Language)를 사용자 정의 URL `path`에 매핑할 수 있습니다. locales는 프로젝트 폴더 구조에 해당하는 한 모든 형식의 문자열이 될 수 있지만 `codes`는 브라우저에서 허용되는 구문을 따라야 합니다.

맞춤 URL 접두사를 정의하려면 `path` 키를 사용하여 `locales` 배열에 객체를 전달하고, 이 URL에 매핑된 언어를 나타내는 `codes`를 전달합니다. 이 경우 `/[locale]/` 폴더 이름은 `path` 값과 정확히 일치해야 하며 URL은 `path` 값을 사용하여 생성됩니다.

이는 언어의 여러 변형 (예: `"fr"`, `"fr-BR"`, `"fr-CA"`)을 지원하고 이러한 모든 변형을 동일한 URL `/fr/` 아래에 매핑하거나 사용자 정의하려는 경우에 유용합니다. (예: `/french/`):

```js title="astro.config.mjs" del={5} ins={6-9}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    locales: [
      'es',
      'en',
      {
        path: 'french', // 슬래시가 포함되지 않음
        codes: ['fr', 'fr-BR', 'fr-CA'],
      },
    ],
    routing: {
      prefixDefaultLocale: true,
    },
  },
});
```

[`astro:i18n` 가상 모듈](#가상-모듈-astroi18n)의 함수를 사용하여 구성 (예: `getRelativeLocaleUrl()`)에 따라 유효한 URL 경로를 계산하는 경우, [해당 `path`를 `locale` 값으로 사용](#사용자-정의-경로에서-url-생성)하세요.

### 브라우저 언어 감지

Astro의 [주문형 서버 렌더링 모드 (`output:'server'` 또는 `output:'hybrid'`)](/ko/guides/server-side-rendering/) 중 하나와 결합된 Astro의 i18n 라우팅을 사용하면 브라우저 언어 감지를 위한 두 가지 속성인 `Astro.preferredLocale` 및 `Astro.preferredLocaleList`에 액세스할 수 있습니다.

이는 브라우저의 `Accept-Language` 헤더와 `locales` (문자열 또는 `codes`)를 결합하여 방문자가 선호하는 언어를 자동으로 적용합니다.

- `Astro.preferredLocale`: Astro는 브라우저의 선호 언어가 `locales` 배열에 포함된 경우, 방문자를 위한 **선호 언어**를 계산할 수 있습니다. 일치 항목이 없으면 이 값은 undefined가 됩니다.
- `Astro.preferredLocaleList`: 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열입니다. 그러면 여러분의 사이트와 방문자 간 호환되는 모든 언어 목록이 생성됩니다. 브라우저가 요청한 언어가 `locales` 배열에 없으면 값은 `[]`입니다. 브라우저가 기본 언어를 지정하지 않으면 이 값은 [`i18n.locales`]가 됩니다.
- `Astro.currentLocale`: `locales` 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 `/[locale]/` 접두사가 포함되어 있지 않으면 값은 기본적으로 `i18n.defaultLocale`이 됩니다.

방문자의 선호도를 성공적으로 일치시키려면 [브라우저에서 사용하는 것](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept-Language)과 동일한 패턴을 사용하여 `codes`를 제공하십시오.

### 대체 전략

Astro의 i18n 라우팅을 사용하면 **대체 라우팅 전략**을 구성할 수 있습니다. 한 언어로 된 페이지가 존재하지 않는 경우 (예: 아직 번역되지 않은 페이지) 404 페이지를 표시하는 대신 언어별로 사용자를 한 언어에서 다른 언어로 리디렉션할 수 있습니다. 이는 아직 모든 경로에 대한 페이지가 없지만 방문자에게 일부 콘텐츠를 제공하려는 경우에 유용합니다.

예를 들어 아래 구성은 누락된 `fr` 경로에 대한 대체 언어로 `es`를 설정합니다. 이는 `src/pages/fr/my-page.astro` 파일이 존재하지 않을때 `example.com/fr/my-page/`에 방문한 사용자가 404 페이지로 이동하지 않고 `example.com/es/my-page/`로 리디렉션되어 콘텐츠를 볼 수 있다는 것을 의미합니다.

```js title="astro.config.mjs" ins={6-8}
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    fallback: {
      fr: 'es',
    },
  },
});
```

Astro는 `src/pages/es/`에 존재하는 모든 페이지에 대해 `src/pages/fr/`에 페이지가 빌드되었는지 확인합니다. 페이지가 아직 존재하지 않으면 해당 `es` 경로로 리디렉션되는 페이지가 생성됩니다.

## 가상 모듈 `astro:i18n`

이 모듈은 프로젝트에 구성된 언어를 사용하여 URL을 생성하는 데 도움이 되는 기능을 제공합니다.

i18n 라우터를 사용하여 프로젝트에 대한 경로를 생성하는 것은 페이지 경로에 영향을 주는 특정 구성 값에 따라 달라집니다. 이러한 기능을 사용하여 경로를 생성할 때 다음에 대한 개별 설정을 고려해야 합니다.

- [`base`](/ko/reference/configuration-reference/#base)
- [`trailingSlash`](/ko/reference/configuration-reference/#trailingslash)
- [`build.format`](/ko/reference/configuration-reference/#buildformat)
- [`site`](/ko/reference/configuration-reference/#site)

또한 `defaultLocale`에 대해 이러한 함수에 의해 생성되어 반환된 URL은 `i18n.routing` 구성을 반영합니다.

`prefixDefaultLocale: true`가 구성된 경우, 생성된 URL에는 URL에 `/lang/` 경로가 포함됩니다. `prefixDefaultLocale: false`로 생성된 URL에는 언어 접두사가 포함되지 않습니다.

### `getRelativeLocaleUrl()`

`getRelativeLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string`

이 함수를 사용하여 언어의 상대 경로를 검색합니다. 해당 언어가 존재하지 않으면 Astro는 오류를 발생시킵니다.

```astro
---
getRelativeLocaleUrl('fr', '');
// /fr 반환

getRelativeLocaleUrl('fr', 'getting-started');
// /fr/getting-started 반환

getRelativeLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
});
// /blog/fr-ca/getting-started 반환

getRelativeLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
  normalizeLocale: false,
});
// /blog/fr_CA/getting-started 반환
---
```

### `getAbsoluteLocaleUrl()`

`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string`

[`site`]에 값이 있을 때 언어의 절대 경로를 검색하려면 이 함수를 사용하세요. [`site`]가 구성되지 않은 경우, 함수는 상대 URL을 반환합니다. 해당 언어가 존재하지 않으면 Astro는 오류를 발생시킵니다.

```astro title="src/pages/index.astro"
---
// `site`가 `https://example.com`로 설정된 경우

getAbsoluteLocaleUrl('fr', '');
// https://example.com/fr 반환

getAbsoluteLocaleUrl('fr', 'getting-started');
// https://example.com/fr/getting-started 반환

getAbsoluteLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
});
// https://example.com/blog/fr-ca/getting-started 반환

getAbsoluteLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
  normalizeLocale: false,
});
// https://example.com/blog/fr_CA/getting-started 반환
---
```

### `getRelativeLocaleUrlList()`

모든 언어에 대한 상대 경로 목록을 반환하려면 [`getRelativeLocaleUrl`](#getrelativelocaleurl)과 같이 이것을 사용하세요.

`getRelativeLocaleUrlList(locale: string, options?: GetLocaleOptions): string[]`

### `getAbsoluteLocaleUrlList()`

`getAbsoluteLocaleUrlList(locale: string, options?: GetLocaleOptions): string[]`

모든 언어에 대한 절대 경로 목록을 반환하려면 [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl)과 같이 이것을 사용하세요.

### `getPathByLocale(locale: string): string`

[사용자 정의 언어 경로](#사용자-정의-언어-경로)가 구성될 때 하나 이상의 `codes`와 연결된 `path`를 반환하는 함수입니다.

### 사용자 정의 경로에서 URL 생성

`locale`이 사용자 정의 경로인 경우 `locale` 값으로 `path`를 사용하세요.

예를 들어, 아래 `locales` 구성에 대한 i18n 도우미 함수에서 `french`를 사용하세요.

```js
locales: ["es", "en", {
  path: "french",
  codes: ["fr", "fr-BR", "fr-CA"]
}],
```

```astro title="src/pages/index.astro"
---
import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from 'astro:i18n';

getRelativeLocaleUrl('french', 'blog'); // /french/blog 반환
---
```

다른 `astro:i18n` 함수는 동일한 구성에 대해 다음 결과를 반환합니다.

```astro title="src/pages/index.astro"
---
getPathByLocale('fr'); // "french" 반환
getPathByLocale('fr-CA'); // "french" 반환
getLocaleByPath('french'); // 구성된 첫 번째 code이기 때문에 "fr"을 반환
---
```

### `getLocaleByPath(path: string): string`

언어 `path`와 연관된 `code`를 반환하는 함수입니다.

### 사용자 정의 경로에 대한 언어 검색

여러 `codes`로 구성된 사용자 정의 경로가 주어지면, 함수는 구성된 **첫 번째** 코드를 반환합니다.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      'en',
      'es',
      'fr',
      {
        path: 'portugues',
        codes: ['pt-AO', 'pt', 'pt-BR'],
      },
    ],
  },
});
```

```astro
---
// src/pages/index.astro
import { getLocaleByPath } from 'astro:18n';
console.log(getLocaleByPath('en')); // "en"를 기록합니다.
console.log(getLocaleByPath('fr')); // "fr"를 기록합니다.
console.log(getLocaleByPath('portugues')); // "pt-AO"를 기록합니다.
---
```

[`site`]: /ko/reference/configuration-reference/#site
[`i18n.locales`]: /ko/reference/configuration-reference/#i18nlocales
